<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<link rel="Stylesheet" type="text/css" media="screen" href="Screen.css" />
	<title>STP_CreateBridge</title>
</head>
<body>
	<h3>STP_CreateBridge</h3>
	<hr />
	<h4>Declaration</h4>
	<pre>BRIDGE* STP_CreateBridge
(
    unsigned int          portCount,
    unsigned int          treeCount,
    const STP_CALLBACKS*  callbacks,
    STP_VERSION           protocolVersion,
    const unsigned char   bridgeAddress [6],
    unsigned int          debugLogBufferSize
);</pre>
	<h4>Summary</h4>
	<p>Creates an STP bridge and returns a BRIDGE* object.</p>
	<h4>Parameters</h4>
	<dl>
		<dt>portCount</dt>
		<dd>The number of ports this bridge will have. Usually equal to the number of physical ports
			present on the device.</dd>
		<dt>treeCount</dt>
		<dd>Number of MSTP spanning trees. Must be 1 in STP or RSTP mode, and 1..64 in MSTP mode.
			<p>
				Passing an invalid value will cause an assertion failure in the function,
				if assertion are enabled in the build options.</p>
		</dd>
		<dt>callbacks</dt>
		<dd>Pointer to an <a href="STP_CALLBACKS.html">STP_CALLBACKS</a>
			structure containing pointers to application-defined STP callbacks.
			<p>
				The STP library 
				makes a copy of this structure, so the application can reuse it after the function 
				returns.</p>
		</dd>
		<dt>protocolVersion</dt>
		<dd>One of the <a href="STP_VERSION.html">STP_VERSION</a> values.
			The library does not support legacy STP (<code>STP_VERSION_LEGACY_STP</code>) as that&#39;s 
			a very old standard; it will most likely 
			never support it.</dd>
		<dt>bridgeAddress</dt>
		<dd>The MAC address of the STP bridge. See the Remarks section at
			<a href="STP_SetBridgeAddress.html">STP_SetBridgeAddress</a> for important information 
			about this address. </dd>
		<dt>debugLogBufferSize</dt>
		<dd>The size of the debug log buffer this function will allocate. Must be >= 2.
			</dd>
	</dl>
	<h4>Return value</h4>
	<dl>
		<dd>A pointer to a BRIDGE object. This pointer is used for uniquely identifying the bridge while
			calling various other STP functions, such as <a href="STP_DestroyBridge.html">STP_DestroyBridge</a>.
		</dd>
	</dl>
	<h4>Remarks</h4>
	<p>
		This functions allocates all the memory required for running the bridge,
		and it does so only using the STP callback <code>
		<a href="StpCallback_AllocAndZeroMemory.html">allocAndZeroMemory</a></code>. No other STP 
		function allocates memory. This allows the application programmer to determine empirically 
		the memory requirement of the STP library for a given bridge. The memory requirement 
		depends, among other things, on the number of ports, the number of spanning trees, and the 
		debug log size. This memory requirement never changes between successive executions of the 
		program.</p>
	<p>
		This function sets all operational parameters 
		(such as ForwardDelay, HelloTime, bridge priority, port priority etc.) to their default values from the STP standard. </p>
	<p>
		This function does not start the bridge (i.e., does not begin execution of the bridge&#39;s
		state machines). The application must explicitly start the bridge by calling <a href="STP_StartBridge.html">
			STP_StartBridge</a>, usually after setting some operational parameters.</p>
	<p>
		Before calling this function, the application must 
		instruct the hardware to stop forwarding STP-specific BPDUs between ports, and forward 
		them instead to to the processor / microcontroller running the application; the 
		application must then pass these incoming BPDUs to the STP library by calling
		<a href="STP_OnBpduReceived.html">STP_OnBpduReceived</a>. The application must also 
		instruct the hardware to tag somehow the incoming BPDUs so as to convey <em>port number 
		information </em>together with the content of the BPDU packet. This is usually realized by 
		writing to the hardware registers of the bridge IC.</p>
	<p>
		It is a good idea to reset the bridge IC before calling this function, so as to ensure 
		that the STP library finds the hardware in a well-defined state.</p>
	<p>
				The debug log text is generated by the STP library code and is passed to the application 
				via <code><a href="StpCallback_DebugStrOut.html">StpCallback_DebugStrOut</a></code>. This callback in turn usually sends this text
				to a PC via some "debug connection". For best performance, this log should be larger
				for packet-based connections such as Ethernet, and smaller for non-packet-based connections
				such as serial.
			</p>
	<p>
				Logging of debug text is disabled when this function returns. 
				The application can explicitly enable it 
				with <a href="STP_EnableLogging.html">STP_EnableLogging</a>.</p>
	<p>
				This function creates a default MST Configuration Identifier as 
				follows:</p>
	<ul>
		<li><em>ConfigurationIdentifierFormatSelector</em> is zero.</li>
		<li><em>ConfigurationName</em> is generated from the <code>bridgeAddress</code> parameter and has the 
			format aa:bb:cc:dd:ee:ff. If the application does not explicitly set a name by calling
			<a href="STP_SetMstConfigName.html">STP_SetMstConfigName</a>, the STP library updates this 
			default name whenever the bridge address is 
			changed later with <a href="STP_SetBridgeAddress.html">STP_SetBridgeAddress</a>. </li>
		<li><em>RevisionLevel</em> is zero.</li>
		<li><em>ConfigurationDigest</em> is 0xAC36177F50283CD4B83821D8AB26DE62, which corresponds to 
			a mapping in which all VIDs are mapped to the CIST, no VID is mapped to any MSTI.</li>
		<li>The mapping of VIDs to MSTIs, which can be retrieved with
			<a href="STP_GetMstConfigTable.html">STP_GetMstConfigTable</a>, is all zeroes.</li>
	</ul>

	<p>
		The STP library is not thread-safe in any way. If the STP library is used in a multi-threaded
		application, it is recommended that all library functions are called from the same
		thread; the library will, in turn, call all its <a href="STP_CALLBACKS.html">callbacks</a>
		on that thread. If the application needs to call library functions from different
		threads, it should use some &quot;STP library lock&quot; before calling any library
		function; the library could then call its callbacks on different threads, and this
		should be kept in mind when writing the callback code.</p>
</body>
</html>
